//! # GridCut - High-Performance Graph Cut Library for Regular Grid Structures
//!
//! GridCut is a Rust implementation of the Boykov-Kolmogorov maximum flow algorithm,
//! optimized for regular 2D and 3D grid graphs. It's designed for applications like
//! image segmentation, volumetric segmentation, and other computer vision tasks that
//! require efficient graph cut computations on grid-structured data.
//!
//! ## Features
//!
//! - **2D Grid Graphs**: Support for 4-connected and 8-connected 2D grids
//! - **3D Grid Graphs**: Support for 6-connected and 26-connected 3D grids (planned)
//! - **Multi-threaded Variants**: Parallel implementations for improved performance
//! - **Type Safety**: Generic over capacity and flow types (i32, i64, f32, f64, etc.)
//! - **Memory Safety**: Leverages Rust's ownership system to prevent common errors
//! - **Cache-Optimized**: Block-based memory layout for improved cache locality
//!
//! ## Quick Start
//!
//! ```rust,no_run
//! use grid_cut_rs::{GridGraph2D4C, Segment};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! // Create a 100x100 grid graph
//! let mut graph = GridGraph2D4C::<i32, i32, i32>::new(100, 100)?;
//!
//! // Set up capacities for each node
//! for y in 0..100 {
//!     for x in 0..100 {
//!         let node = graph.node_id(x, y)?;
//!         
//!         // Set terminal capacities (source and sink)
//!         graph.set_terminal_cap(node, 10, 5)?;
//!         
//!         // Set neighbor capacities
//!         if x < 99 {
//!             graph.set_neighbor_cap(node, 1, 0, 8)?; // Right neighbor
//!         }
//!         if y < 99 {
//!             graph.set_neighbor_cap(node, 0, 1, 8)?; // Down neighbor
//!         }
//!     }
//! }
//!
//! // Compute maximum flow
//! graph.compute_maxflow();
//!
//! // Get results
//! let flow = graph.get_flow();
//! let node = graph.node_id(50, 50)?;
//! let segment = graph.get_segment(node);
//!
//! println!("Maximum flow: {}", flow);
//! println!("Node (50,50) is in segment: {:?}", segment);
//! # Ok(())
//! # }
//! ```
//!
//! ## Bulk Capacity Setting
//!
//! For better performance when initializing large graphs, use `set_caps` to set
//! all capacities at once:
//!
//! ```rust,no_run
//! use grid_cut_rs::GridGraph2D4C;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let width = 100;
//! let height = 100;
//! let mut graph = GridGraph2D4C::<f32, f32, f32>::new(width, height)?;
//!
//! let num_pixels = width * height;
//! let cap_source = vec![10.0; num_pixels];
//! let cap_sink = vec![5.0; num_pixels];
//! let cap_left = vec![8.0; num_pixels];
//! let cap_right = vec![8.0; num_pixels];
//! let cap_up = vec![8.0; num_pixels];
//! let cap_down = vec![8.0; num_pixels];
//!
//! graph.set_caps(&cap_source, &cap_sink, &cap_left, &cap_right, &cap_up, &cap_down)?;
//! graph.compute_maxflow();
//! # Ok(())
//! # }
//! ```
//!
//! ## Graph Types
//!
//! ### 2D Graphs
//!
//! - [`GridGraph2D4C`]: 2D grid with 4-connected neighbors (up, down, left, right)
//! - [`GridGraph2D8C`]: 2D grid with 8-connected neighbors (includes diagonals)
//! - [`GridGraph2D4CMT`]: Multi-threaded variant of 4-connected 2D grid
//!
//! ### 3D Graphs (Planned)
//!
//! - `GridGraph3D6C`: 3D grid with 6-connected neighbors (face neighbors)
//! - `GridGraph3D26C`: 3D grid with 26-connected neighbors (face, edge, and corner)
//! - `GridGraph3D6CMT`: Multi-threaded variant of 6-connected 3D grid
//!
//! ## Algorithm
//!
//! The library implements the Boykov-Kolmogorov maximum flow algorithm, which consists
//! of three main phases that repeat until no augmenting path exists:
//!
//! 1. **Growth Phase**: Search for an augmenting path from source to sink using BFS
//! 2. **Augmentation Phase**: Push flow along the found path
//! 3. **Adoption Phase**: Restore the search tree structure
//!
//! The algorithm is optimized for grid topology with:
//! - Block-based memory layout for cache efficiency
//! - Timestamp-based path validation to avoid redundant traversals
//! - Two-level orphan queue for efficient adoption
//!
//! ## Examples
//!
//! See the `examples/` directory for complete working examples:
//!
//! - `image_segmentation_2d.rs`: Binary image segmentation using 2D graph cuts
//! - `volume_segmentation_3d.rs`: Volumetric segmentation (placeholder for 3D implementation)
//!
//! Run examples with:
//! ```bash
//! cargo run --example image_segmentation_2d
//! ```
//!
//! ## Performance Considerations
//!
//! - Use `set_caps()` for bulk initialization instead of individual `set_terminal_cap()` calls
//! - Choose appropriate numeric types (i32 for integer capacities, f32 for floating-point)
//! - Consider multi-threaded variants for large grids (>1000x1000)
//! - The block-based memory layout provides good cache locality automatically
//!
//! ## Error Handling
//!
//! All fallible operations return `Result<T, GridCutError>`. Common errors include:
//!
//! - [`GridCutError::InvalidDimensions`]: Grid dimensions must be positive
//! - [`GridCutError::InvalidCoordinates`]: Coordinates out of bounds
//! - [`GridCutError::InvalidNodeId`]: Node ID out of range
//! - [`GridCutError::InvalidOffset`]: Invalid neighbor offset for connectivity type
//! - [`GridCutError::InvalidCapacityArrayLength`]: Array length doesn't match grid size

pub mod types;
mod internal;
mod grid_cut;

// Re-export public types
pub use types::{GridCutError, GridGraph, Segment};
pub use grid_cut::grid_2d_4c::GridGraph2D4C;
pub use grid_cut::grid_2d_8c::GridGraph2D8C;
pub use grid_cut::grid_2d_4c_mt::GridGraph2D4CMT;
